---
title: TDinsight 参考手册
sidebar_label: TDinsight
toc_max_heading_level: 4
---

import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

TDinsight 是使用 [Grafana] 对 TDengine TSDB 进行监控的解决方案。

TDengine TSDB 通过 taosKeeper 将服务器的 CPU、内存、硬盘空间、带宽、请求数、磁盘读写速度、慢查询等信息定时写入指定数据库。通过 Grafana 和 TDengine TSDB 数据源插件，TDinsight 将集群状态、节点信息、插入及查询请求、资源使用情况等进行可视化展示，为开发者实时监控 TDengine TSDB 集群运行状态提供了便利。本文将指导用户安装 TDengine TSDB 数据源插件及部署 TDinsight 可视化面板。

## 前置条件

首先检查下面服务：

- TDengine TSDB 已经安装并正常运行，此仪表盘需要 TDengine TSDB 3.0.0.0 及以上，并开启监控上报配置，具体配置请参考：[TDengine TSDB 监控配置](../taosd/#监控相关)。
- taosAdapter 已经安装并正常运行。具体细节请参考：[taosAdapter 参考手册](../taosadapter)
- taosKeeper 已安装并正常运行。具体细节请参考：[taosKeeper 参考手册](../taoskeeper)
- Grafana 服务已安装并正常运行。我们建议您使用最新的 Grafana 版本，TDInsight 支持 Grafana 7.5 及以上版本。
  :::info

  下文介绍中，都以 Grafana v11.0.0 版本为例，其他版本功能可能有差异，请参考 [Grafana 官网](https://grafana.com/docs/grafana/latest/)。

  :::

然后记录以下信息：

- taosAdapter 集群 REST API 地址，如：`http://localhost:6041`。
- taosAdapter 集群认证信息，可使用用户名及密码。
- taosKeeper 记录监控指标的数据库名称。

## 安装 TDengine TSDB 数据源插件和配置数据源

安装 Grafana TDengine TSDB 数据源插件和配置数据源的步骤请参考：[与  Grafana 集成](../../../third-party/visual/grafana/#安装-grafana-plugin-并配置数据源)

## 导入 TDinsightV3 仪表盘

- **推荐方式**：在配置好数据源后，点击“Settings”右侧的“Dashboards”，会显示数据源自带的仪表盘，然后选择“TDengine for 3.x”右侧的“Import”进行导入。  
![TDinsight V3 import](./assets/import-tdinsightv3.webp)  

- 使用 Dashboard ID 导入：在 Grafana 主界面左侧，依次点击“Dashboards”Tab、右上角“New”选项下的“Import”，输入“TDengine for 3.x”仪表盘的 Dashboard ID `18180`，进行导入。
- 使用 JSON 配置导入：
    1. 先去 [TDinsight for 3.x](https://grafana.com/grafana/dashboards/18180-tdinsight-for-3-x/) 下载 JSON 文件。
    2. 在 Grafana 主界面左侧，依次点击“Dashboards”Tab、右上角“New”选项下的“Import”。
    3. 在“Import via dashboard JSON model”部分粘贴上刚才下载的 JSON 文件内容，最后点击“Import”导入。

导入成功后可以进入这个 Dashboard，在左上角“Log from”选项中选择 taosKeeper 中设置的记录监控指标的数据库就可以看到监控结果。

## TDinsightV3 仪表盘详情

TDinsight 仪表盘旨在提供 TDengine TSDB 相关资源的使用情况和状态，比如 dnodes、mnodes、vnodes 和数据库等。
主要分为集群状态、DNodes 概述、MNode 概述、请求、数据库、DNode 资源使用情况和 taosAdapter 监控信息。下面我们分别详细介绍。  

### 集群状态

这部分指标包括集群当前信息和状态。

![TDengine TSDB Database TDinsight mnodes overview](./assets/TDinsight-1-cluster-status.webp)

指标详情（从上到下，从左到右）：

- **First EP**：当前 TDengine TSDB 集群中的`firstEp`设置。
- **Version**：TDengine TSDB 服务器版本（master mnode）。
- **Expire Time** - 企业版过期时间。
- **Used Measuring Points** - 企业版已使用的测点数。
- **Databases** - 数据库个数。
- **Connections** - 当前连接个数。
- **DNodes/MNodes/VGroups/VNodes**：每种资源的总数和存活数。
- **Classified Connection Counts**：当前活跃连接数，按用户、应用和 ip 分类。
- **DNodes/MNodes/VGroups/VNodes Alive Percent**：每种资源的存活数/总数的比例，启用告警规则，并在资源存活率（1 分钟内平均健康资源比例）不足 100% 时触发。
- **Measuring Points Used**：启用告警规则的测点数用量（社区版无数据，默认情况下是健康的）。

### DNodes 概述

这部分指标包括集群 dnode 基本信息。

![TDengine TSDB Database TDinsight mnodes overview](./assets/TDinsight-2-dnodes.webp)

指标详情：

- **DNodes Status**：`show dnodes` 的简单表格视图。
- **DNodes Number**：DNodes 数量变化。

### MNode 概述

这部分指标包括集群 mnode 基本信息。

![TDengine TSDB Database TDinsight mnodes overview](./assets/TDinsight-3-mnodes.webp)

指标详情：

1. **MNodes Status**：`show mnodes` 的简单表格视图。
2. **MNodes Number**：类似于`DNodes Number`，MNodes 数量变化。

### 请求统计

这部分指标包括集群执行 sql 的统计指标。

![TDengine TSDB Database TDinsight requests](./assets/TDinsight-4-requests.webp)

指标详情：

1. **Select Request**：select 请求数。
2. **Delete Request**：delete 请求数。
3. **Insert Request**：insert 请求数。
4. **Inserted Rows**：实际插入行数。
5. **Slow Sql**：慢查询数，可以在顶部分时长段过滤。

### 表统计

这部分指标包括集群中表的统计指标。

![TDengine TSDB Database TDinsight database](./assets/TDinsight-5-database.webp)

指标详情：

1. **STables**：超级表数量。
2. **Total Tables**：所有表数量。
3. **Tables**：所有普通表数量随时间变化图。
4. **Tables Number Foreach VGroups**：每个 VGroups 包含的表数量。

### DNode 资源使用情况

这部分指标包括集群所有数据节点资源使用情况展示，每个数据节点为一个 Row 进行展示。。

![TDengine TSDB Database TDinsight dnode-usage](./assets/TDinsight-6-dnode-usage.webp)

指标详情（从上到下，从左到右）：

1. **Uptime**：从创建 dnode 开始经过的时间。
2. **Has MNodes?**：当前 dnode 是否为 mnode。
3. **CPU Cores**：CPU 核数。
4. **VNodes Number**：当前 dnode 的 VNodes 数量。
5. **VNodes Masters**：处于 master 角色的 vnode 数量。
6. **Current CPU Usage of taosd**：taosd 进程的 CPU 使用率。
7. **Current Memory Usage of taosd**：taosd 进程的内存使用情况。
8. **Max Disk Used**：taosd 所有数据目录对应的最大磁盘使用率。
9. **CPU Usage**：进程和系统 CPU 使用率。
10. **RAM Usage**：RAM 使用指标时间序列视图。
11. **Disk Used**：多级存储下每个级别使用的磁盘（默认为 level0 级）。
12. **Disk IO**：磁盘 IO 速率。
13. **Net IO**：网络 IO，除本机网络之外的总合网络 IO 速率。

### taosAdapter 监控

这部分指标包括 taosAdapter rest 和 websocket 请求统计详情。

![TDengine TSDB Database TDinsight monitor taosadapter](./assets/TDinsight-8-taosadapter.webp)

指标详情：

1. **Total**：总请求数
2. **Successful**：总成功数
3. **Failed**：总失败数
4. **Queries**：总查询数
5. **Writes**：总写入数
6. **Other**：总其他请求数

还有上述分类的细分维度折线图。

### 预配置告警规则自动导入

涛思总结用户使用经验，整理出 14 个常用的告警规则（alert rule），能够对集群关键指标进行监测并及时上报指标异常、超限等告警信息。  
从 TDengine TSDB server 3.3.4.3 版本（tdengine-datasource 3.6.3）开始，TDengine TSDB Datasource 支持预配置告警规则自动导入功能，用户可将 14 个告警规则一键导入 Grafana（11 及以上版本），直接使用。  
预配置告警规则导入方法如下图所示，在 tdengine-datasource setting 界面，打开“Load Tengine Alert”开关，点击“Save & test”按钮后，插件会自动加载上述告警规则，规则会放入以数据源名称 + “-alert”的 grafana 告警目录中。如不需要，关闭“Load TDengine Alert”开关，点击“Clear TDengine Alert”旁边的按钮则会清除此数据源已导入的所有告警规则。

![TDengine TSDB Alert](./assets/TDengine-Alert.webp)  

导入后，点击 Grafana 左侧“Alert rules” ，可查看当前所有告警规则。
用户只需配置联络点（Contact points），即可获取告警通知。联络点配置方法见[告警配置](https://docs.taosdata.com/third-party/visual/grafana/#%E5%91%8A%E8%AD%A6%E9%85%8D%E7%BD%AE)。

![Alert-rules](./assets/Alert-rules.webp)

14 个告警规则具体配置如下：  

| 规则名称 | 规则阈值 | 无监控数据时的行为 | 数据扫描间隔 |持续时间 | 执行 SQL              |
| ------ | --------- | ---------------- | ----------- |------- |----------------------|
|dnode 节点的 CPU 负载 | 均值 > 80%|触发告警|5 分钟|5 分钟 |`select now(), dnode_ep, last(cpu_system) as cpu_use from log.taosd_dnodes_info where _ts >= (now- 5m) and _ts < now partition by dnode_ep`|
|dnode 节点的的内存 |均值 > 60%|触发告警|5 分钟|5 分钟|`select now(), dnode_ep, last(mem_engine) / last(mem_total)  * 100 as taosd from log.taosd_dnodes_info where _ts >= (now- 5m) and _ts <now partition by dnode_ep`|
|dnode 节点的磁盘容量占用 | > 80%|触发告警|5 分钟|5 分钟|`select now(), dnode_ep, data_dir_level, data_dir_name, last(used) / last(total)  * 100 as used from log.taosd_dnodes_data_dirs where _ts >= (now - 5m) and _ts < now partition by dnode_ep, data_dir_level, data_dir_name`|
|集群授权到期 |< 60 天 | 触发告警|1 天|0 秒|`select now(), cluster_id, last(grants_expire_time) / 86400 as expire_time from log.taosd_cluster_info where  _ts >= (now - 24h)  and _ts < now  partition by cluster_id having first(_ts) > 0`|
|测点数达到授权测点数|>= 90%|触发告警|1 天|0 秒|`select  now(), cluster_id,  CASE  WHEN max(grants_timeseries_total)  > 0.0 THEN max(grants_timeseries_used)  /max(grants_timeseries_total) * 100.0   ELSE 0.0    END AS result from log.taosd_cluster_info where _ts >= (now - 30s) and _ts < now partition by cluster_id  having timetruncate(first(_ts), 1m) > 0`|
|查询并发请求数 | > 100|不触发报警|1 分钟|0 秒|`select now() as ts, count(*) as slow_count from performance_schema.perf_queries`|
|慢查询执行最长时间（无时间窗口） |> 300 秒 | 不触发报警|1 分钟|0 秒|`select now() as ts, count(*) as slow_count from performance_schema.perf_queries where exec_usec>300000000`|
|dnode 下线 |total != alive|触发告警|30 秒|0 秒|`select now(),  cluster_id, last(dnodes_total)  - last(dnodes_alive) as dnode_offline  from log.taosd_cluster_info where _ts >= (now -30s) and _ts < now partition by cluster_id having first(_ts) > 0`|
|vnode 下线 |total != alive|触发告警|30 秒|0 秒|`select now(),  cluster_id, last(vnodes_total)  - last(vnodes_alive) as vnode_offline  from log.taosd_cluster_info where _ts >= (now - 30s) and _ts < now partition by cluster_id having first(_ts) > 0`|
|数据删除请求数 |> 0|不触发报警|30 秒|0 秒|`select  now(), sum(`count`)  as`delete_count`from log.taos_sql_req  where sql_type = 'delete' and _ts >= (now -30s) and _ts < now`|
|Adapter RESTful 请求失败 |> 5|不触发报警|30 秒|0 秒|`select now(), sum(`fail`) as`Failed`from log.adapter_requests where req_type=0 and ts >= (now -30s) and ts < now`|
|Adapter WebSocket 请求失败 |> 5|不触发报警|30 秒|0 秒|`select now(), sum(`fail`) as`Failed`from log.adapter_requests where req_type=1 and ts >= (now -30s) and ts < now`|
|dnode 数据上报缺少 |< 3|触发告警|180 秒|0 秒|`select now(),  cluster_id, count(*) as dnode_report  from log.taosd_cluster_info where _ts >= (now -180s) and _ts < now  partition by cluster_id  having timetruncate(first(_ts), 1h) > 0`|
|dnode 重启 |max(update_time) > last(update_time)|触发告警|90 秒|0 秒|`select now(), dnode_ep, max(uptime) - last(uptime) as dnode_report  from log.taosd_dnodes_info where _ts >= (now - 90s) and _ts < now partition by dnode_ep`|

用户可参考上述告警规则，根据自己业务需求进行修改与完善。  
Grafana7.5 及以下版本，Dashboards 与 Alert rules 功能合在一起，而之后的新版本两个功能是分开的。为兼容 Grafana7.5 及以下版本，TDinsight 面板中增加了 Alert Used Only 面板，仅 Grafana7.5 及以下版本需要使用。

![Alert Used Only](./assets/Alert-Used-Only.webp)

## 升级

下面三种方式都可以进行升级：

- 用图形界面，若有新版本，可以在“TDengine TSDB Datasource”插件页面点击 update 升级。
- 按照手动安装步骤自行安装新的 Grafana 插件和 Dashboard。
- 通过重新运行 `TDinsight.sh` 脚本升级到最新的 Grafana 插件和 TDinsight Dashboard。  

## 卸载

针对不同的安装方式，卸载时：

- 用图形界面，在“TDengine TSDB Datasource”插件页面点击“Uninstall”卸载。
- 通过 `TDinsight.sh` 脚本安装的 TDinsight，可以使用命令行 `TDinsight.sh -R` 清理相关资源。
- 手动安装的 TDinsight，要完全卸载，需要按照顺序清理以下内容：
  1. Grafana 中的 TDinsight Dashboard。
  2. Grafana 中的 Alert rules 告警规则。
  3. Grafana 中的 Data Source 数据源。
  4. 从插件安装目录删除 `tdengine-datasource` 插件。

## 附录

### TDinsight.sh 详细说明

下面是 TDinsight.sh 的用法详细说明：

```text
Usage:
   ./TDinsight.sh
   ./TDinsight.sh -h|--help
   ./TDinsight.sh -n <ds-name> -a <api-url> -u <user> -p <password>

Install and configure TDinsight dashboard in Grafana on Ubuntu 18.04/20.04 system.

-h, -help,          --help                  Display help

-V, -verbose,       --verbose               Run script in verbose mode. Will print out each step of execution.

-v, --plugin-version <version>              TDengine TSDB datasource plugin version, [default: latest]

-P, --grafana-provisioning-dir <dir>        Grafana provisioning directory, [default: /etc/grafana/provisioning/]
-G, --grafana-plugins-dir <dir>             Grafana plugins directory, [default: /var/lib/grafana/plugins]
-O, --grafana-org-id <number>               Grafana organization id. [default: 1]

-n, --tdengine-ds-name <string>             TDengine TSDB datasource name, no space. [default: TDengine TSDB]
-a, --tdengine-api <url>                    TDengine TSDB REST API endpoint. [default: http://127.0.0.1:6041]
-u, --tdengine-user <string>                TDengine TSDB user name. [default: root]
-p, --tdengine-password <string>            TDengine TSDB password. [default: taosdata]

-i, --tdinsight-uid <string>                Replace with a non-space ASCII code as the dashboard id. [default: tdinsight]
-t, --tdinsight-title <string>              Dashboard title. [default: TDinsight]
-e, --tdinsight-editable                    If the provisioning dashboard could be editable. [default: false]
```

大多数命令行选项都可以通过环境变量获得同样的效果。

| 短选项 | 长选项                     | 环境变量                     | 说明                                                    |
| ------ | -------------------------- | ---------------------------- | ------------------------------------------------------- |
| -v     | --plugin-version           | TDENGINE_PLUGIN_VERSION      | TDengine TSDB 数据源插件版本，默认使用最新版。               |
| -P     | --grafana-provisioning-dir | GF_PROVISIONING_DIR          | Grafana 配置目录，默认为`/etc/grafana/provisioning/`    |
| -G     | --grafana-plugins-dir      | GF_PLUGINS_DIR               | Grafana 插件目录，默认为`/var/lib/grafana/plugins`。    |
| -O     | --grafana-org-id           | GF_ORG_ID                    | Grafana 组织 ID，默认为 1。                             |
| -n     | --tdengine-ds-name         | TDENGINE_DS_NAME             | TDengine TSDB 数据源名称，默认为 TDengine。                  |
| -a     | --tdengine-api             | TDENGINE_API                 | TDengine TSDB REST API 端点。默认为`http://127.0.0.1:6041`。 |
| -u     | --tdengine-user            | TDENGINE_USER                | TDengine TSDB 用户名。 [默认值：root]                        |
| -p     | --tdengine-password        | TDENGINE_PASSWORD            | TDengine TSDB 密码。 [默认：taosdata]                        |
| -i     | --tdinsight-uid            | TDINSIGHT_DASHBOARD_UID      | TDinsight 仪表盘`uid`。 [默认值：tdinsight]             |
| -t     | --tdinsight-title          | TDINSIGHT_DASHBOARD_TITLE    | TDinsight 仪表盘标题。 [默认：TDinsight]                |
| -e     | --tdinsight-editable       | TDINSIGHT_DASHBOARD_EDITABLE | 如果配置仪表盘可以编辑。 [默认值：false]                |

:::note
新版本插件使用 Grafana unified alerting 功能，`-E` 选项不再支持。
:::

假设您在主机 `tdengine` 上启动 TDengine TSDB 数据库，HTTP API 端口为 `6041`，用户为 `root1`，密码为 `pass5ord`。执行脚本：

```bash
./TDinsight.sh -a http://tdengine:6041 -u root1 -p pass5ord
```

如果要监控多个 TDengine TSDB 集群，则需要设置多个 TDinsight 仪表盘。设置非默认 TDinsight 需要进行一些更改： `-n` `-i` `-t` 选项需要更改为非默认名称，如果使用 内置短信告警功能，`-N` 和 `-L` 也应该改变。

```bash
sudo ./TDengine.sh -n TDengine-Env1 -a http://another:6041 -u root -p taosdata -i tdinsight-env1 -t 'TDinsight Env1'
```

请注意，配置数据源、通知 Channel 和仪表盘在前端是不可更改的。您应该再次通过此脚本更新配置或手动更改 `/etc/grafana/provisioning` 目录（这是 Grafana 的默认目录，根据需要使用`-P`选项更改）中的配置文件。

特别地，当您使用 Grafana Cloud 或其他组织时，`-O` 可用于设置组织 ID。 `-G` 可指定 Grafana 插件安装目录。 `-e` 参数将仪表盘设置为可编辑。
